/*
 *
 *      Copyright (c) 2018-2025, lengleng All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 *  this list of conditions and the following disclaimer.
 *  Redistributions in binary form must reproduce the above copyright
 *  notice, this list of conditions and the following disclaimer in the
 *  documentation and/or other materials provided with the distribution.
 *  Neither the name of the pig4cloud.com developer nor the names of its
 *  contributors may be used to endorse or promote products derived from
 *  this software without specific prior written permission.
 *  Author: lengleng (wangiegie@gmail.com)
 *
 */

package com.pig4cloud.pig.admin.service;

import cn.hutool.core.lang.tree.Tree;
import com.baomidou.mybatisplus.extension.service.IService;
import com.pig4cloud.pig.admin.api.entity.SysDept;
import com.pig4cloud.pig.admin.api.vo.DeptExcelVo;
import com.pig4cloud.pig.common.core.util.R;
import org.springframework.validation.BindingResult;

import java.util.List;

/**
 * 部门管理服务接口
 * <p>
 * 提供部门的核心业务逻辑处理，包括部门树形结构管理、部门关系维护、
 * Excel导入导出等功能。支持部门的层级管理和组织架构查询
 * </p>
 *
 * @author lengleng
 * @since 2018-01-20
 */
public interface SysDeptService extends IService<SysDept> {

	/**
	 * 查询部门树菜单
	 * <p>
	 * 构建部门的树形结构，支持按部门名称模糊查询。
	 * 返回的树结构包含完整的父子关系，用于前端展示组织架构
	 * </p>
	 * 
	 * @param deptName 部门名称，支持模糊查询，为空时查询所有部门
	 * @return 部门树结构列表
	 */
	List<Tree<Long>> getDeptTree(String deptName);

	/**
	 * 根据部门ID删除部门
	 * <p>
	 * 删除指定部门及其所有子部门，同时更新闭包表关系。
	 * 如果部门下存在用户，则不允许删除
	 * </p>
	 * 
	 * @param id 要删除的部门ID
	 * @return 删除操作是否成功，成功返回true，失败返回false
	 */
	Boolean removeDeptById(Long id);

	/**
	 * 导出部门Excel数据列表
	 * <p>
	 * 查询所有部门信息并转换为Excel导出格式。
	 * 导出数据包含部门名称、上级部门、排序等完整信息
	 * </p>
	 * 
	 * @return 部门Excel视图对象列表
	 */
	List<DeptExcelVo> exportDepts();

	/**
	 * Excel批量导入部门数据
	 * <p>
	 * 支持通过Excel批量创建部门，自动处理父子关系和闭包表。
	 * 导入时会验证部门名称唯一性和父部门存在性
	 * </p>
	 * 
	 * @param excelVOList Excel解析后的部门数据列表
	 * @param bindingResult 数据校验结果，包含格式错误等信息
	 * @return 导入结果，包含成功数量和失败详情
	 */
	R importDept(List<DeptExcelVo> excelVOList, BindingResult bindingResult);

	/**
	 * 获取指定部门的所有后代部门列表
	 * <p>
	 * 基于闭包表结构快速查询部门的所有子部门和孙部门。
	 * 用于部门权限继承、批量操作等场景
	 * </p>
	 * 
	 * @param deptId 部门ID
	 * @return 后代部门列表，包括直接子部门和所有孙级部门，不存在则返回空列表
	 */
	List<SysDept> listDescendants(Long deptId);

}
